Day 24：我的「專案憲法」——每一條留得下來的規則，背後都有一次教訓

昨天資安篇收在一句話：把散落在一次次對話裡的判斷，沉澱成文件與規範。這份規範，我主要寫在一個叫 CLAUDE.md 的檔案裡——它是 Claude Code 每次啟動、還沒動手之前就會先讀進去的常駐指令。我在裡面寫清楚這個專案怎麼做事、哪些寫法禁用、踩過哪些坑，於是每開一個新對話，AI 不必從零認識這個專案，我也不用把同一套規矩再交代一遍。我私下把它叫「專案憲法」。

方法論這一段，就從這裡開始——而且我不想空談「一份好憲法該長怎樣」，直接把我在用的那份攤開來講。我的憲法其實分兩層：一份全域的、所有專案共用，加上每個專案自己的一份。全域那份大約一千一百行，看起來很多，但它不追求完整或漂亮，只追求一件事：把我踩過的坑和做過的決定，變成 AI 每一次的預設。

第一種內容：AI 自己推斷不出來的專案決定

最基本的一類，是那些「AI 讀程式碼也未必推得出、但我希望它每次都照辦」的專案慣例。舉我全域憲法裡的實例：前端一律用某個特定框架的特定寫法、UI 元件庫固定那幾套、後端 ORM 固定某個版本某種定義格式；資料模型檔一律放在某個固定路徑、畫面檔按一套固定的目錄結構長出來。

這些規則本身沒什麼「智慧」，但它們解決一個很實際的問題：沒有它們，AI 每個 session 都會用它自己覺得合理的方式來一套，這個對話 Vue、下個對話 jQuery，風格四散。 寫進憲法，等於一次把「這個專案的長相」定下來，之後每次產出都一致。這類是憲法的地基。

第二種內容：我的判斷準則，寫成一道梯子

再上一層，我把「該怎麼決定要不要寫某段程式」這件事，也固定成了一套準則。這是我憲法裡我自己最喜歡的一段，它長這樣（原文照登，只是我私下給它取了個代號）：

開發決策原則：撰寫任何程式碼前，依序確認以下梯子，停在第一個成立的階層：

1. 這個需要存在嗎？需求不明確或未來才需要 → 跳過（YAGNI）
2. 這個 codebase 已有？現有的 helper、function → 重用，不重寫
3. 標準函式庫有？Node.js 內建能解決 → 用它
4. 原生平台功能有？<input type="date"> 優於日期套件、CSS 優於 JS、DB constraint 優於 AP 層驗證
5. 已安裝的套件有？現有依賴能解決 → 用它，不引入新套件
6. 一行能解決？→ 就一行
7. 以上都不是 → 才寫最小可用的實作

底下還跟著兩句，是這段的靈魂：

重要： 梯子是在理解問題之後才執行，不是取代理解。
懶於解法，不懶於理解。驗證、錯誤處理、資安、存取控制永遠不在省略範圍內。

我特別看重這一段，是因為它把一個很難言傳的東西——「怎樣才算把程式寫好」——變成了 AI 每次都會照著走的優先序。沒有它，AI 的天性是「你要一個功能，我就刻一個給你」，很容易一上來就造一個其實內建函式庫早就有的輪子。有了這道梯子，它會先往上問「這需要存在嗎」「有沒有現成的」，一路問到第七階才自己動手。這是我把自己的判斷，變成了它的預設判斷。

但真正讓一條規則活下來的，是它背後的「為什麼」

如果這篇只能留一句，就是這句：光寫規則不夠，要把規則存在的原因也寫進去。 我憲法裡最有生命力的幾條，旁邊都掛著一段看似多餘的「為什麼」。

第一個例子，一次真實的事故。 我有一條關於 Vite 建置設定的規則，核心是「輸出目錄不得落在輸入路徑底下」。這條規則單看很抽象，但它後面接著一段事故紀錄——我其中一個專案，就因為輸出目錄設在靜態資源目錄底下、又有背景監看程序沒關掉，每次建置把上一輪產物又複製進去，滾成一個自我餵養的迴圈，最後炸出兩千兩百多層巢狀目錄、四十六萬個檔案、將近 12 GB，清理花了兩個半小時。（就是 Day 10 記錄過的那件事。）有了這個數字，下一個看到這條規則的人——不管是半年後的我，還是某個 AI session——才不會覺得它小題大作、手癢把它拿掉。

第二個例子，一個單看會矛盾的規則。 我憲法裡寫著「開發機搜尋檔案時忽略大小寫差異，但寫 require() 時務必注意大小寫」。這兩句擺一起像在打架，直到你看見它的原因：開發環境是 Windows（檔名不分大小寫），部署環境是 Linux（分），大小寫寫錯了本機一切正常、上線才爆。原因一寫上去，這條規則就從「莫名其妙」變成「非遵守不可」。

第三個例子，一條專門用來防 AI 的規則。 我寫了一條：「專案裡既有的 callback 風格是歷史遺留寫法，不代表撰寫慣例，新增或修改時一律改用 async/await，不要模仿舊寫法。」這條的原因，是我摸清了 AI 的一個天性——它會參照現場既有程式碼的風格。 如果不寫這句，它看到滿專案的舊 callback，會很自然地照著寫，把技術債一路複製下去。這條規則的本質是：我知道 AI 會在哪裡犯錯，所以先寫一條規則，站在那裡等它。

這三條的共同點是：規則會過期、也一定會被質疑。當有人開始懷疑「這條還有必要嗎」的時候，決定它能不能動的，正是那段被寫下來的原因。 有原因，他判斷得出來能不能拿掉；沒原因，他要嘛盲從一條自己不理解的規則，要嘛自作主張改掉、然後在同一個坑裡再摔一次。

兩層憲法：全域是通則，專案可以推翻它

前面說我的憲法分兩層，這裡給一個最能說明的實例。

我的全域憲法明明白白寫著「新畫面一律用 Vue3，禁止在新畫面使用某個過時框架」。但我手上有些專案，本身還沒完成遷移、目前整套都還跑在那個舊框架上。這些專案自己的 CLAUDE.md，就直接覆寫了全域這一條，寫著：本專案維持舊框架、不主動改寫；在既有頁面擴充功能時維持舊框架、不得混入新框架；只有全新建立的頁面才使用 Vue3；同一頁禁止兩種框架並存。

這就是兩層憲法的意義：通則寫一次、到處適用；特例各自管好各自的，而且有權推翻通則。 全域規範定的是「理想上該怎麼做」，專案憲法補的是「這個專案的現實是什麼」。少了分層，你要嘛把一堆專案特例塞進全域、互相打架，要嘛每次開專案都重講一遍現實。順帶一提，我同一套系統會佈署給不同單位，那些專案的憲法結構幾乎一樣、只差各自的識別碼和少數特例——分層之後，共通的部分我只維護一份。

但要說清楚：憲法是「強預設」，不是「鐵律」

這裡得誠實補一刀，免得把憲法講得太神。寫進 CLAUDE.md 的規則，AI 每次都讀得到、也強烈傾向照做，但這跟程式碼裡的 if 不一樣——它不是「一定會執行」的保證，只是「大幅提高照做機率」的強預設。模型還是可能漏看、可能被眼前的任務帶著走。

最容易被漏掉的，正是「動手做某件事之前，先做 X」這種前置程序規則。我自己就寫過一條：每個工作階段真正動手改東西之前，先問我要不要建一條新分支。結果實際跑起來，它好幾次直接跳過這一問、埋頭就開始改——因為它的注意力被「你要我做的那件事」整個吸走了，那道「先問一下」的閘門就這麼被略過。這在語言模型上是通例，不是規則寫得不好。

這反而是整個系列的另一個註腳：你不能寫下一條規則，就以為它一定被執行、然後把人抽走。 規則降低了出錯的機率，但沒有消滅它，該盯的地方還是得盯。而如果某件事是「非做到不可、不能靠模型剛好記得」的，那光寫進憲法就不夠了，得換一種更硬的機制——像 Claude Code 的 hook，它是在特定時機由程式確定性地觸發、而不是靠模型自覺，才擋得住「一定要先建分支」這種事。憲法負責「大多數時候都照著我的判斷走」，hook 負責「這幾件事絕對不能出錯」，兩者是不同層級的工具。

這一天的分工

這篇沒什麼「AI 出錯、我糾正」的來回，因為憲法這件事，主導的本來就是人。AI 是那個照著憲法幹活的對象；憲法寫什麼、為什麼這樣寫、哪一條能動——從頭到尾是我的判斷。

但這正好是整個系列主軸的另一面。前面二十三天我一直在講「判斷不能外包給 AI」；而 CLAUDE.md 是這句話的反面——它是我把判斷「存下來」的地方，好讓 AI 每一次都站在這些判斷之上做事，而不是每次都要我從頭判斷一遍。 判斷不能外包，但判斷可以沉澱、可以複用；憲法就是那個容器。資安篇那些關於日誌、稽核、唯讀掛載的判斷，後來也一條條寫進了某個專案的憲法裡——那份文件，就是那幾天工作的沉澱物。

而一份憲法好不好，不看它寫了多少條，看它每一條有沒有帶著自己的理由。規則是死的，會過期、會被質疑；讓它在被質疑時還站得住、被維護時不被誤刪的，是它背後那個「為什麼」。

明天談維護。因為這份文件會長雜草——過期的規則、多餘的強調、其實 AI 自己就能推斷的內容。上週我用兩個工具把它從頭審了一遍，結果它們抓到的東西，跟我原本以為的很不一樣：其中一筆，工具的信心標得最高，卻判斷錯了——而它錯的原因，正好是我今天講的這件事的反面：那條規則，我當初漏寫了它的「為什麼」。